Background

The docs-builder changelog add command currently outputs files that follow the naming structure using by Elastic Agent: https://github.com/elastic/elastic-agent/tree/main/changelog/fragments

However, Elasticsearch changelogs currently use a different format (i.e. the filenames match the PR numbers): https://github.com/elastic/elasticsearch/tree/main/docs/changelog

It seems reasonable for the tool to accommodate either option.

Summary

• Added the --use-pr-number option to the docs-builder changelog add command.

Changes Made

• ChangelogInput.cs: Added UsePrNumber property to track when the option is enabled.
• ChangelogCommand.cs:
  • Added --use-pr-number parameter (boolean, defaults to false)
  • Added XML documentation for the parameter
  • Passed the value to ChangelogInput
• ChangelogService.cs:
  • Added validation to ensure --pr is provided when --use-pr-number is used
  • Added ExtractPrNumber() helper to extract PR numbers from:
    • Full URLs: https://github.com/owner/repo/pull/123
    • Short format: owner/repo#123
    • PR number only: 123 (when --owner and --repo are provided)
  • Updated filename generation to use {prNumber}.yaml when --use-pr-number is set, instead of {timestamp}-{slug}.yaml
• Documentation:
  • docs/contribute/changelog.md:
    • Added --use-pr-number to the command options list
  • Added info about the default filename format ({timestamp}-{sanitized-title}.yaml) and how to use --use-pr-number to create filenames like {pr-number}.yaml
  • docs/cli/release/changelog-add.md:
    • Added --use-pr-number option documentation in the Options section
    • Included a note that --pr must be provided when using this option

Usage

This command creates a file named 767653383-esql-fix-extent-reading-when-missing.yaml:

./docs-builder changelog add --pr 140034 \
  --repo elasticsearch --owner elastic \
  --products "elasticsearch 9.3.0" \
  --output ~/my-path/GitHub/elasticsearch/docs/changelog/ \
  --type bug-fix

This command creates a file named 140034.yaml:

./docs-builder changelog add --pr 140034 \
  --repo elasticsearch --owner elastic \
  --products "elasticsearch 9.3.0" \
  --output ~/my-path/GitHub/elasticsearch/docs/changelog/ \
  --type bug-fix
  --use-pr-number

Here are more examples:

# Using PR number as filename
docs-builder changelog add --pr 12345 --owner elastic --repo elasticsearch --products "elasticsearch 9.2.0" --use-pr-number

# Or with full PR URL
docs-builder changelog add --pr https://github.com/elastic/elasticsearch/pull/12345 --products "elasticsearch 9.2.0" --use-pr-number

The implementation includes validation and error handling. The build completed successfully, and the help output shows the new option.

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-1 agent